test: cover the shipped surface, and make the coverage figure mean something - #30

The refusal for a marker path already occupied describes what it found,
and describe_type/1 fell through to "a #{type}" for anything that is not
a directory or a symlink. File.lstat/1 answers :other for a named pipe,
a socket and anything else the emulator has no name for, so the shipped
message read "there is already a other at that path".

The catch-all stays for :device, where "a device" reads correctly.

Pinned with a fifo at the marker path, which is the one :other a test
can create with no privileges and no file mode - a mode fixture here
would only sometimes describe the state it names.

Co-Authored-By: Claude <noreply@anthropic.com>

Castle.Commands and Castle.Peer both carry failing branches that no
case reached. These are the ones a fixture can produce without a file
mode, which the suite refuses on the grounds that root and some
filesystems ignore one - a fixture that only sometimes describes the
state it names is a test that only sometimes tests anything.

In Castle.Commands: a version directory that is a file rather than a
directory; a node whose which_releases/0 reports neither a current nor
a permanent release, which the restart classification has to answer
about before the refusal is made; a relup entry the classification
cannot read, walked past rather than raised on; a symlink and a fifo at
the marker path; a marker already there whose first line is empty; a
marker claimed between unclaimed/3 and the publish, where publish/2
refusing rather than replacing is the whole of the defence against the
second VM the node-local lock cannot reach; an :enoent from the
marker removal rather than from the read; a throw and an exit out of
install_release/1 with the marker stranded; and the two indeterminate
root comparisons that come from the second path rather than the first.

In Castle.Peer: a release file holding more than one term and one that
will not parse; a sys.config that will not parse, which is the only
reason format_error/1 has a clause for a reason that is not an atom; a
dangling symlink at sys.config.pristine, which publish/2 refuses
rather than following - File.write/2 there creates the target and fills
it with the configuration; a write through a closed handle, which is
why written/3 is :file.write/2 and not IO.binwrite/2; a chmod that
cannot land because the name has gone; a model whose mode cannot be
read; a directory whose mode cannot be read; and a working directory
that cannot be created.

Every one of these was mutation-checked: the branch it covers was
broken, the test was confirmed to fail, and the branch restored.

Co-Authored-By: Claude <noreply@anthropic.com>

AGENTS.md gains an account of what mix test --cover measures now that
test/support is out of it, the lib-only figure and its per-module
breakdown, why the threshold is 85 rather than 90, and why --cover is
not part of mix precommit.

And the part that closes castle#8: what is left uncovered, branch by
branch, with the reason each is a decision. Most are filesystem
failures no fixture can arrange without a mode; the rest are the
compiler default-argument clauses for arities nothing calls, a target
release carrying an older Castle.Peer, and the booted release that is
Forecastle e2e work.

RELEASE.md records the refusal-message fix, which is the only
user-visible outcome here.

Co-Authored-By: Claude <noreply@anthropic.com>

Three tests, for two branches the residual-coverage inventory got wrong
and one it dismissed.

closed/2 was executed but not discriminated. The closed-handle test
fails both the write and the close, and `with :ok <- written, :ok <-
closed` reports the write - so replacing closed/2 error clause with :ok
left the whole file green while the inventory claimed the clause was
uncovered and the report showed it hit. Telling the two apart needs a
handle whose write succeeds and whose close does not, which is a
process: File.io_device/0 is `pid | file_descriptor`, and :file.write/2
sends a pid an io request where File.close/1 sends a file_request. The
new test asserts the close own reason and that the file was not
narrowed, which is the "mode only once both succeeded" half of fill/3.

publish/2 generic error needed none of the modes or mounts it was
grouped with: File.ln/2 with a staging file that is not there answers
:enoent and creates no destination.

call/2 unrecognised answer is the cross-version contract, and reaching
it needs a castle application built for the target alone.
SyntheticRelease.stub_castle/2 builds one with :compile.forms/2 rather
than from Elixir source - the module is named Castle.Peer, so compiling
it from source would load the stub over the running one. build/2 gains
:override to point lib/<app>-<vsn> at it while leaving the release file
alone.

Co-Authored-By: Claude <noreply@anthropic.com>

The 85 threshold sat below the 87.95% it was meant to floor, so it
ratcheted nothing and licensed a thirteen-line regression. It is now
88.58 - the measured figure, 419 of 473 relevant lines. One uncovered
line added to lib gives 88.40% and fails; that was checked rather than
assumed.

And precommit runs test --cover, so the floor is a gate. Nothing else
ran it, and a floor nothing enforces is decoration. CI test matrix
stays on a plain mix test: cover line attribution can differ between
Elixir versions, so the figure is enforced on the one pinned toolchain
the precommit job uses.

90% would need 426 covered, seven more. Five of the seven can only come
from the compiler generated clauses for defaulted arities nothing
calls - measured, not assumed: calling the intermediate arities covers
all five and reaches 89.64%. Each is a delegation whose defaults are a
subset of an arity already called, so those cases would asserted
nothing. That is the move this project does not make.

The mechanism claim was also wrong. cover does not need distribution:
:cover.start/0 works in a VM with no node name. What happens is that
Mix instruments the modules loaded on this node and the peer loads the
target own beams, which nothing instrumented - and cover only route to
another VM is a distributed node, which the peer deliberately is not.

Co-Authored-By: Claude <noreply@anthropic.com>

The residual-coverage list was written from analysis rather than from
the report, and it was wrong three ways: it claimed closed/2 was
uncovered while the report showed the clause hit, and it grouped
publish/2 generic error and call/2 unrecognised answer with paths
needing modes or mounts when neither needs either. All three are now
covered, and the list is rebuilt line by line against a regenerated
cover/ - stale HTML from before the test/support exclusion is how the
inconsistency survived, so the note says to delete it first.

The mechanism claim is corrected: cover is not unable to run in a
non-distributed VM, it is that Mix instruments this node and nothing
instruments the peer.

The remaining 21 observable lines are split into the five compiler
generated clauses and the sixteen that need a mode, a device node or a
provider sabotaging the working directory, with the arithmetic for why
90% is out of reach honestly rather than absolutely.

Also records why fill/3 needs three different handles to pin its three
steps, and why stub_castle/2 compiles with :compile.forms/2.

Co-Authored-By: Claude <noreply@anthropic.com>

The floor was enforced in only one place that ran it - mix precommit, on
whatever Elixir the contributor happened to have - and nothing in CI checked
it at all. The test matrix ran a plain mix test and the precommit job is
pinned to the one version that agreed with the number, so CI stayed green
while a clean tree failed the gate on Elixir 1.20. A drift nothing watches is
a drift the next contributor finds.

The newest cell of the test matrix now exports coverage and checks the floor.
It is the lowest reporter, so it trips first on attribution drift. Every other
cell stays on a plain mix test: seven readings that disagree by version would
be noise rather than signal. The include entry augments the existing 1.20/29
cell rather than adding a job.

Two steps rather than one mix test --cover, so the step that goes red names
what broke without opening the log - exporting cannot fail on the threshold,
and mix test.coverage cannot fail on a test. The job name carries the same
information.

Verified on 1.20.3/OTP 29: export exits 0, the check reports 88.40% and exits
0, and with the floor raised to 89 the check exits 3 - so it is a gate and not
decoration.

Co-Authored-By: Claude <noreply@anthropic.com>